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PREFACE 


The purpose of this manual is to provide a detailed overview of the Multics 
Resource Management facility, including the Resource Control Package, and to 
explain why and how it is used. 


The Multics Administrators' Manual-Resource Control, Order No. CC74 is the 
primary Resource Management Facility document, which explains to administrators 
the details of running the facility, including maintenance and restoration of 
the registries. 


Non-administrative users of the facility can gain sufficient understanding 
from the material contained in this manual. Administrative users additionally 
require MAM Resource Control to perform their duties of setting up and 
maintaining the environment. 


The reference manuals for Multics administrators are collectively referred 
to as the Multics Administrators' Manual (MAM). Throughout this document, 
references to the MAM are as follows: 


Document Referenced In Text As 
Project MAM Project 

(Order No. AK51) 

Registration and Accounting MAM Accounting 

(Order No. AS68) 

System MAM System 

(Order No. AK50) 

Resource Control MAM RCP 

(Order No. CC74) 

Communications MAM Communications 


(Order No. CC75) 


The MAM Project is a guide to the operation of programs in the 
project-administration area. The information in this manual is of interest not 
only to project administrators but also to accounting administrators (who may 
function as project administrators) and to system administrators (who may 
function in any administrative capacity). 


The information and specifications in this document are 
subject to change without notice. This document contains 
information about Honeywell products or services that may 
not be available outside the United States. Consult your 
Honeywell Marketing Representative. 


© Honeywell Information Systems Inc., 1981 File No.: 1L13 
CT38-00 


The MAM Accounting is a guide to the operation of Multics billing and 
accounting programs. It is necessary that both the accounting and system 
administrators know how to perform the Multics billing operations. 


The MAM System is a guide to the overall administration of the Multics 
system. This manual discusses the contents of administrative directories and 
data bases and special user identities (such as the daemons), describes 
installation parameters and system logs, explains the various tasks that are the 
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carry out these responsibilities. Also, the functions of the system security 
administrator are explained in the MAM System. 


The MAM RCP is a guide to the management of the use of peripheral I/0 
devices and the physical volumes which can be mounted on these devices. This 
manual describes registering and deregistering such resources, controlling the 
access to these resources, and the pertinent administrative commands. 


The MAM Communications is a guide to the operation of the Multics 
Communication System (MCS). The manual includes information on terminal types, 
line types, and channel management. 


The primary reference manuals for user and system programmers of the 
Multics system are collectively referred to as the Multics Programmers' Manual 
(MPM). These manuals contain general information and programs needed by an 
administrator and are, therefore, referenced throughout this document. For 
convenience, these references are as follows: 


Document Referenced In Text As 


Reference Guide MPM Reference Guide 


(Order No. AG9T) 


Commands and Active Functions MPM Commands 


(Order No. AG92) 


Subroutines MPM Subroutines 


(Order No. AG93) 


Subsystem Writers' Guide MPM Subsystem Writers' Guide 
(Order No. AK92) 


Peripheral Input/Output MPM Peripheral I/0 
(Order No. AX49) 


Communications Input/Output MPM Communications I/0 


(Order No. CC92 
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SECTION 1 


INTRODUCTION 


This manual contains the information necessary to understand the Resource 
Management Facility from a user's point of view and to acquire, reserve, and use 
resources as well as releasing them. 


Section 2 describes how to use Resource Management, using as an example 
tapes at a sample site. Section 3 describes the user interfaces in detail and 
gives an overview of administrative interfaces. Section 4 contains descriptions 
of user commands; Section 5 contains the user subroutines. 


OVERVIEW OF THE RESOURCE MANAGEMENT FACILITY 


The resource control package (RCP) resource management facility is the part 
of the Multics operating system that manages the use of peripheral I/O devices 
(such as tape drives, printers, and punches) and physical volumes that can be 
mounted on these devices (such as tape reels, forms, and disk packs). These 
resources are managed by programs located in the administrative ring (ring 1), 
and run in the user's process. 


The resource management f 


aci 
resources, which includes deregistr 


ity handles registration and acquisition of 
re) 


C 
t on and release. 


RCP software reserves, assigns, and mounts resources; also demounts, 
unassigns, and cancels reservations. 
The hierarchical level of these functions are: 
1 register 
Resource Management 
2 acquire 
3 reserve 
4 assign 
Resource Control 
5 detach 
4 unassign 
3 cancel 
2 release 


Resource Management 
j deregister 
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The function of RCP is to control the access to and usage of I/O devices. 
RCP executes in ring 1. Access to the various functions of RCP are controlled 
by the ring 1 gates that must be used to call RCP. One of the primary functions 
of RCP as a device manager is to control access to the I/O interfacer (IOI). In 
order to do this, no IOI gate entries are available to perform device 
attachments, detachments, and other privileged administrative functions. User 
ring programs, therefore, call RCP in order to request IOI to perform these 
functions. 


An important part of RCP is Resource Management--the ability to retain 
registration information for all resources that it controls. It does this by 
providing administrative interfaces for the registration of resources (see 
Section 3). Registration of a resource provides information such as: what type 
of resource this is, what its name is, which attributes it possesses, or in what 
access class range the resource can be used. Once a resource is registered, 
users may acquire it; system administrators can also acquire it to a user (or to 
the system pool) at the time it is registered (described in the MAM RCP). The 
act of acquisition makes a user the owner of the resource--liable for all 
charges to that resource and in control of discretionary access to the resource. 


Another important feature of RCP is its ability to control access to the 
various resources that it manages (where a resource is either a device ora 
volume). It does this through the use of access control segments (ACSs). An 
ACS is a zero-length segment whose ACL and ring brackets are used to define the 
discretionary and intraprocess access to aresource. At a site's discretion, 
additional features of RCP can be enabled to provide nondiscretionary access 
control for resources. If this is done, access is also controlled by the AIM 
access class range of a resource (see "Access Control" below). 


The resource control functions performed by RCP are: 


1. maintain resource information 

2. control access to resources 

3. reserve and cancel reservation of resources 
y, assign and unassign devices 

5. attach and detach devices 

6. perform special device control functions 


Reservation, Assignment, and Attachment 


The functions reserve, assign, and attach are organized into hierarchical 
levels. Defaults are provided at each level so that users not desiring to 
exercise features specifie to a level do not have to concern themselves with 
that level. 


1 reserve 
2 assign 


3 attach 
3 detach 
2 unassign 
1 cancel 


The first level involves the reservation of resources by processes. Tape 
drives, disk drives, tape volumes and disk volumes ean be reserved. 
Reservations are process-specifiec and remain in effect until the process 
requests a cancellation. Reservation implies that a process temporarily has 
exclusive rights to a resource. This exclusive right means that no other 
process can use that resource for the duration of the reservation. Reservation 
does not necessarily imply that a resource is actually being used. Multiple 
resources can be reserved with one reservation. 
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Assignment, like reservation, is process-specific and lasts. until 
unassignment or process termination. Any resource type can be assigned. An 
aSSignment also gives a process temporary exclusive rights to a device. 
Assignment does not necessarily mean that a device is currently being used. 
That is the function of the next level, attachment. Only one resource can be 
assigned per assignment. 


A resource cannot be used until it is attached. When RCP is called to 
attach aresource, it initiates communication with the ring 0 subsystem that 
actually provides the use of the resource. Before the attachment is completed, 
RCP performs all initialization necessary to allow the attaching process. to 
begin using the. resource. ._For devices, this involves...attaching the device via 
IOI and making sure that the device is ready and that any volume needed has been 
determined to be accessible, mounted, and authenticated. 


The hierarchical relationship among reservation, assignment, arid attachment 
implies that a higher-level function (e.g., reservation) can stan¢ alone, while 
a lower-level function (e.g., attachment) can only be performed after all 
higher-level functions have been performed. RCP can perform the following 
device reservation, assignment, and attachment functions: 


iy Reserving a resource, This means that no other process can use it 
during this period of time. 


2s Explicitly assigning a reserved device. The device is assigned to a 
process but is not attached. 


a6 Attaching an explicitly assigned device. 


4, Attaching an unassigned device. Since a device cannot be attached 
until it is assigned, RCP automatically reserves and assigns the 
device and then performs the attachment. The device is said to be 
implicitly assigned. 


55 Detaching an implicitly assigned device. After the device is 
detached, RCP automatically unassigns the device. 


6. Detaching an explicitly assigned device. The device is detached but 
is not unassigned. 


‘e Explicitly unassigning a device. If the device is ettached, it is 
first detached and then unassigned. 


8s Cancelling reservation of a resource. 


The rules stated above imply that I/O modules do not have to be concerned 
with the assignment or unassignment of devices. They need to be concerned with 
only the attachment and detachment of a device. RCP, however, does allow the 
above rules’ to be overridden. When detaching a device an I/0 module can tell 
RCP to retain the device assignment regardless of whether the device was 
explicitly or implicitly assigned. 


When a= process terminates, RCP automatically detaches and unassigns all 
devices currently assigned to that process and cancels any reservations for that 
process. 
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The reservation of resources and cancellation of reservations are done from 
command level via the reserve resource and cancel resource commands or by using 
the -resource control argument with the enter_abs request command. The explicit 
assignment and unassignment of devices is done from command level via the 
assign_resource and unassign_resource commands. The listing of reservations, 
assignments, and attachments is done from command level via the list_resources 
command. The enter_abs request command is described in the MPM commands; the 
other commands named here are described in Section 4 of this manual. 


SUMMARY OF RESOURCE MANAGEMENT FACILITY ACTIONS 


nc a | en 


Here is a description of the preliminary actions that you may take when you 
want to use a resource. 


Acquisition 


Once a resource is registered by the system administrator, it may be 
acquired by a user. When a user acquires a resource, he is contracting with the 
system to become the accounting owner of the resource. In other words, the 
person who acquires the resource uSually agrees to pay a fee for the right to 
control the access to that resource. 


After registering a resource, the system administrator may acquire it in 
the name of the system or a user, deciding who is allowed to use that resource. 
Devices (such as tape drives and printers) and "scratch" volumes (e.g., tapes in 
the system pool) are usually acquired to the system. System-owned resources 
such as devices and scratch volumes are for use by all users. For other 
resources such as’ tape reels and disk packs, the system administrator normally 
chooses to leave most of these in an unacquired state so that users may acquire 
these resources on an individual basis. 


In order to control the operation of the resource management facility, an 
administrative table exists that can be adapted to the specific needs of a 
particular Multics' site. This table is referred to as the resource type 
description table (RTDT). The table is generated from a_ source language 
description, called the resource type master file (RTMF), ordinarily prepared by 
a system administrator. The contents of the RITDT can be examined via the 
display rtdt command. (The RTDT and the display_rtdt command are described in 
detail in the MAM RCP.) 


Resource Reservation 


Users may reserve resources by scheduling with RCP to obtain exclusive 
rights to aresource for a period of time. RCP enables users to reserve 
resources or groups of resources through the use of the reserve resource command 
(described in Section 4). A reservation takes effect immediately and it lasts 
until either the user's process is terminated or the reservation is specifically 
cancelled via the cancel resource command (described in Section 4). After 
invoking reserve resource, the user has exclusive rights to the resource(s). 


Tape volumes, tape drives, disk volumes, and disk drives can be reserved. 
Tape and disk volumes are specified at the time of reservation by name; tape and 
disk drives are specified by either name or attributes. In the case of disk 
drives, the only acceptable attribute is model. For tape drives, acceptable 
attributes are model, track, and density. Suitable values for the 
above-mentioned attributes may be found by using the list _resource types command 
(described in Section 4). 
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To cancel reservations, users invoke the list resources command to obtain 
the reservation identifier, and then invoke the cancel resource command with the 
reservation identifier to effect the cancellation. Administrators can perform 
privileged cancellations; that is, if the administrator has proper access, it is 
possible to cancel reservations belonging to other users. 


Device Assignment 


The RCP interface for device assignment allows the caller to request the 
assignment of a Specific dévice, or “any appropriate device of a specified type. 
To request the assignment of a specific device the caller must ask for the 
device by name. To request the assignment of an appropriate device of a 
specified type, the caller must specify the characteristics that the assigned 
device must have. RCP selects a device for assignment based on the following 
functional algorithm. 


1. If the caller has requested a device by name and if this device is 
already assigned to the calling process, the assignment is aborted. 


2. RCP tests all of the devices of the specified type. RCP counts the 
number of these devices that are appropriate; appropriate and 
accessible; and appropriate, accessible and available. These 
requirements are discussed below: 


ae appropriate: A device is considered to be appropriate if it has 
the device characteristics specified by the caller. In testing 
each device, RCP does not try to match any device characteristics 
that are not specified by the caller. If a device is asked for 
by name, only the device name is considered. 


b. accessible: A device is considered to be accessible if the 
calling process has rw RCP effective access to the device. 


coe available: A device is considered to be available for assignment 
if it is not currently assigned to any process or reserved by 
another process. 


3. Having tested each of these requirements, RCP then makes additional 
tests to see if a device can be assigned. If the assignment cannot be 
made, RCP returns an error _table_ code that tells the caller why the 
assignment aborted. The tests that RCP makes at this time are 
described below: 

a. If there are no appropriate devices, the caller is told that the 
requested resource (device) is not known to RCP. 


b. If there are no appropriate and accessible devices, the caller is 
told that he does not have access to the requested resource 
(device). 


Ce If there are no appropriate, accessible and available devices, 
the caller is told that the requested resource (device) is not 
available at this time. 


d. If this assignment causes the device limits (see “Device Limits# 
below) to be exceeded, the user is told that he has exceeded the 
limit. 


4, If all the tests described above are passed successfully, the device 
assignment is made. RCP selects the most advantageous device from the 
list of devices that were found to be appropriate and accessible and 
available. It makes this selection based on the following rules: 


ae If this is a type of device that has volumes and if the caller 
specified a volume name to use in the device selection and if any 
device in the list currently has that volume mounted, RCP selects 
that device. 
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b. If the first case is not true, RCP selects the device that has 
been idle for the longest amount of time. 


Having assigned the device, RCP returns all of the characteristics of this 
device to the caller. 


Device Attachment 


The RCP interface for device attachment allows the caller’ to request a 
device in the same manner described for device assignment. It can ask for a 
specific device by name or it can ask for any appropriate device of a specified 
type. One difference is that if this device is a type that uses volumes, the 
caller must specify the name of the volume to attach. For assignments, the 
specification of a volume is optional. 


RCP tests allof the devices of the specified type that are already 
assigned by the requesting process. If the specific device or any appropriate 


device is already assigned to this process, RCP attaches that device. If no 
suitable device is already assigned to the requesting process, RCP automatically 
attempts to assign a Suitable device to this process. If no device can be 


assigned then the attachment is aborted. If the attachment is for a device type 
that uses volumes, RCP checks to see if the specified volume is already attached 
to this process or any other process. If the volume is already attached, RCP 
aborts the attachment. 


Once RCP has found a suitable assigned device or has assigned one, it 
begins the real work of attaching the device. This involves calling IOI to 
perform the ring 0 device attachment. If the device is a type that uses 
volumes, RCP tells the operator to mount the specified volume if it is not 
already mounted on the proper device. Before the attachment is completed, RCP 
makes sure that the proper volume has been mounted and that any write protection 
mechanism provided by the device is set correctly. When all of this 
initialization work has been completed, RCP calis IOI to set the workspace and 
time-out limits and to promote the validation level of the device. Until this 
is done, the IOI validation level for the device is the RCP validation level 
(ring 1). Thus no program in a higher ring can successfully call IOI to use 
this device until RCP tells IOI to promote it. RCP returns’ all of the device 
characteristics of the attached device and all of the information needed to 
communicate with IOI about this device. 


RESOURCE NAMING CONVENTIONS 


While the Multics Resource Management Facility implementation allows 
resource names to be any ASCII string of up to 32 characters, there are 
restrictions placed on some of these names by other sources. The remainder of 
this section describes the details of these resource naming conventions. 


Device Names 


Each device has a unique name. Device names are of one of the following forms: 


SSSS_XX 
dddd 


The first form is used for devices that share multiplexed I/O channels such 
as disk and tape devices. The latter is used for all other devices. 
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In the case of disk and tape device names the name is composed of the 
subsystem name, ‘'ssss't in the text above, and the device number, 'xx' above. 
The subsystem name is defined by the site in the configuration via a PRPH card 
(see MOH) and the device number is assigned by the Field Engineering 
Representative when the hardware is installed. 


All other devices are also defined in the configuration deck. In this case 
the PRPH card defines the device itself. These device types include: consoles, 
printers, card readers, card punches, and special devices. 


The four character restrictions listed above are due to the fact that 
character fields on configuration cards are limited to four characters (one 


Volume Names 


Volume names are unique within their volume type (e.g., no two tape volumes 
may have the same name). They may be up to 32 characters in length. The only 
reserved volume names are "scratch" and "T&D Volume" which are used to designate 
scratch volumes for disk and tape. A scratch tape is one of the unmarked tapes 
in an unreserved pool that is used for "seratch"--that is, no information is 
saved on it from session to session. After every use, it is demounted and 
returned to the system pool. "T&D Volume" is used for special label processing 
for online Test and Diagnostics, and its use for attachments requires special 
privilege.: 


ACCESS CONTROL 


There are three types of access control on Multics: discretionary access 
eontrol, which is regulated by access control lists (ACL); nondiscretionary 
access control, which is regulated by the access isolation mechanism (AIM); and 
intraprocess access control, which is regulated by the ring structure. (For 
detailed information on types of access, see the MPM Reference Guide.) 


Access Control Segments 


An important feature of RCP is its ability to control access to the various 
resources that it manages. It does this through the use of access control 
segments (ACSs). An ACS is a zero length segment whose ACL and ring brackets 
are used to define the discretionary access to a resource. RCP uses an ACS for 
each resource that it controls; however, an ACS can be shared by more than one 
resource. The name of an ACS consists of a name plus the suffix, acs (e.g., 
tape 01.acs). There are no restrictions on ACS names other than the required 
suffix. The user creates an ACS and generates/manipulates its ACL with the 
create, set_acl, and delete _acl commands and ring brackets with the 
set_ring brackets command (see the MPM Commands). 


The pathname of the ACS for a resource is usually specified when it is 
acquired (see the register_resource command and the acquire resource command in 
Section 4 of this manual). The specified ACS can later be changed or 
unspecified so that the resource (again) has no ACS via the set resource command 
(see Section 4). If the ACS has not been specified or does not exist, access is 
by default rew for the owner of the resource and null for all other users (see 
access modes in the glossary below). 


RCP uses the ACS along with other nondiscretionary controls (AIM) to 
determine the RCP effective access to a resource. 
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Access Class Ranges 


Access class ranges are used by RCP to specify that a _ process within a 
range of authorizations can use a particular resource. 


An access class range is simply a pair of AIM access classes separated by a 
colon. The first value of the pair is the minimum access class and the second 
is the maximum access class. If only a single access class is specified when an 
access class range is expected, the minimum and maximum access class values are 
both the same (i.e., a range of one value). The second access class of the pair 
(the maximum) must be greater than or equal to the first (the minimum) according 
to the aim_check subroutine (see the MPM Subroutines). 


There are some interesting results which occur when categories are used in 
an access class range. For example, a process with authorization of: 


level2,categoryl 
would not be able to use a resource whose access class range was: 
levell,categoryi1,category2:level3,category1,category2,category3 


where level3 is greater than level2, which is greater than levell. This is due 
to the fact that the authorization of the process is isolated from the minimum 
of the access class range. In order to allow this process access’ to the 
resource in question, the range would have to exclude category2 or the user 
would have to have category2 authorization. In general, to include categories 
within an access class range, both the minimum and maximum must include the 
categories desired. If combinations of categories are desired, the minimum 
should list only required categories and the maximum should include all 
categories allowed. For example, the access class range: 


levell,category1l:level3,category1,category2,category3 


allows read and write access to any levell, level2, or level3 process with 
categoryl and any combination of category2 and category3. 


RCP Effective Access 


Viewed separately, each type of access control answers the same question, 
"What access does a particular process have for a particular item?" The access 
mode granted a process to a resource by discretionary access control (the ACL) 
is known as the raw access mode. 


The way RCP determines effective access to a resource for a process differs 
from the regular Multics method of determining effective access as follows. 
First, the effective access to the ACS for the resource is determined as for any 
segment. If the ACS does not exist, the user appears to have read, execute, and 
write access if he is the owner of the resource, or null access if he is not the 
owner. Then, two further checks are made. First, the current authorization of 
the process is compared to the maximum access class of the resource. If write 
access is not allowed (as defined by the write allowed _ subroutine) then write 
and execute access are denied and only read is allowed. Next, the current 
authorization of the process is compared to the minimum access class of the 
resource. If read access is not allowed (as defined by the read_allowed_ 
subroutine) then all access is denied. The resulting access is termed the RCP 
effective access to the resource. One final restriction enforced by RCP is 
that, in order to use a device, the RCP effective access must include both read 
and write to that device (a restriction not imposed on volumes). 
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For example, the following table illustrates some examples of RCP effective 
access. In the examples below, L1, L2, L3 and L4 represent sensitivity levels 
and c1, ¢e2, c3, and c4 represent categories. (This discussion mostly concerns 
devices--volumes should never be given multiclassed access class range.) 


Table 1-1. RCP Effective Access 


Effective Current Resource RCP 
Access Process Access Effective 
to ACS Authorization Class Range Access 
rew L1 Cbeis rew 

re L1 | ths I) re 

rew L1 Beth3 null 
rew L3 L22L3 rew 

rw L4 L22L3 r 

re L4 E223 r 

rw L2,¢1 LTsL48 r 

rw L2,¢c2 ~ L1,¢1:L4,¢e1,¢e2 null 
rw be3e 1523 LA. elt Lae cer 

rw | Bee | L1,¢c1:L4,e1,c2 rw 


A user must have write RCP effective access to the resource named to 
perform any modification on the status of the resource. In addition, the user 
must have execute effective access to the resource named to modify protected 
attributes. Only the accounting owner may modify the ACS path. 


For more information on AIM, access classes, authorizations, and 
comparisons involving access classes and authorizations, see the MPM Reference 
Guide. The access class range mentioned above is specified by the -access class 
control argument, which can be specified in the register_resource command (see 
the MAM RCP), and the acquire resource and set resource commands (described 
See = =, + oe meee sae = 
later in tnisS manual). 


Manipulating RCP Effective Access 


Since the access control mechanisms described above operate together to 
determine the RCP effective access of a process, there are actions that the 
user, as well as an administrator, can perform to control this effective access. 


First, the user creates an ACS via the create command. Then, the desired 
ACL for that segment is established using the set_acl command to add desired ACL 
entries, and the delete acl command to delete entries. (The above three 
commands are described in the MPM Commands.) To further affect the ACS, the 
user may modify its ring brackets by using the set_ring brackets command 
(descrihed in the MPM Suhsystem Writers! Guide). The system security 


~~ See eet 


administrator sets the AIM access class range of the resource itself at the time 
it is registered using the register_resource command and can change it by using 
the set_resource command. 
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ACQUIRING RESOURCES 


When a system administrator registers a resource, he may simultaneously 
cause it to be acquired; that is, designate who will become the accounting owner 
of that resource. He may immediately acquire it on behalf of either a specific 
user or to the system. Otherwise, he may leave it in the free pool, and the 
resource can then be acquired from this pool. 


Acquisition to the System Pool 


eee eS 


Resources that are to be owned by the system, such as devices and scratch 
volumes, may be acquired to the system pool upon registration. System-owned 
resources are usually set up so that they are shareable among all users. I/0 
devices, such as tape drives, printers, and _ punches, are examples of 
system-owned resources. 


Acquisition by User 


Any resource that is not resident in the system or free pools is acquired 
by a User_id (Person_id.Project_id). 


Acquisition Upon Registration 


As a convenience, a system administrator may register a resource and 
acquire it in one step. The MAM RCP describes this process in detail. 


SITES NOT ENABLING RESOURCE MANAGEMENT 


If the system administrator has chosen not to enable Resource Management 
the preceding discussion of access control can be simplified since no resources 
can be registered. 


Nondiscretionary access control is not enforced in this case. There are no 
ACSs for volumes, and all users are assumed to have both read and write access 
to any volume. The ACS for a device can be found in >system_control_1>rep and 
is named device name.acs (e.g., tape _01.acs). Only the discretionary and 
intraprocess access (ACL and ring brackets) is considered in determining access 
to a device. 


DEVICE LIMITS 


In addition to controlling which processes may have access to a device, RCP 
will enforce a limit to the number of devices of a given type that a single 
process may have assigned at one time. This limit is enforced according to the 
following rules: 

1. The limit is not enforced for system processes. 


2. The limit for each device type is an installation-defined value. It 
is currently specified on PRPH (peripheral) configuration cards. 


3. Currently, only tape drive devices actually have such a limit defined. 
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RCP will also enforce a limit to the total number of devices of a given 
type that may be assigned to non-system processes at one time. RCP enforces 
this limit in order to ensure that a certain number of devices of each device 
type are either assigned by a system process or available for assignment by a 
system process. This limit is enforced according to the following rules: 


HES The number of devices of each device type that RCP will reserve for 
system processes are installation defined values. They are currently 
specified on PRPH configuration cards. 


2. Currently, the only class reserved for system processes is tape 
drives. Only tape drives with certain characteristics (nine-track 
tape. drives) are reserved, since the backup facility uses only 
nine-track tapes. 


I/O Workspaces 


Due to the nature of the Multics virtual memory and its supporting I/0 
hardware, I/O operations such as "read tape" or "write disk" require all pages 
of memory referenced by the I/O operation to be in main memory during the 
operation--that is, no paging is done during execution of the I/O operation. To 
accomplish this, all channel programs and physical record buffer areas are 
located in a special segment known as an I/O workspace segment. The ring 0 I/0 
software, IOI, guarantees that all pages of the workspace are present in main 
memory before starting the I/O operation and remain there for the duration of 
the operation. 


RCP will control the maximum workspace size associated with each device 
type. System processes, privileged processes, and users on the ACL of the ACS 
named workspace.acs in the directory >system_control_1>rep can request up to the 
privileged maximum workspace size. All others can request up to the normal 
maximum workspace size. Requests for a workspace larger than is allowed result 
in errors. The table below lists the workpace maximums that are enforced. 


Table 1-2. I/0 Workspaces 


Privileged Maximum Normal Maximum 

device type words bytes words bytes 
tape_drive 45056 180224 3072 12288 
disk drive 45056 180224 2048 8192! 
printer 45056 180224 1024 4096! 
punch 45056 180224 1024 4096! 
reader 45056 180224 1024 4096! 
special 45056 180224 1024 4096! 
console 45056 180224 1024 4096! 


Tie workspace size is affected by using the -block control argument to 
those I/O modules that support it. This control argument is used to specify the 
maximum physical record/block size to be processed. In all cases some overhead 
for channel programs and I/0 module control information must be taken into 
consideration. When -block is not specified or supported the individual I/0 
modules choose an appropriate default. In the case of commands that use I/0 
modules, either the command, some argument or input to the command, or the I/0 
module may specify/imply in some way the workspace size (for example by 
supplying -block in an attach description). 
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GLOSSARY 


access class 
An access isolation mechanism (AIM) attribute that denotes’ the 
sensitivity of information contained in a segment, directory, 
multisegment file; message in amessage segment; contained on a 
volume; or processed using a device. An access class is associated 
with an entry for its lifetime. 


access class range 
The access range defined by two access classes, including the access 
classes between them. See "Access Class Ranges" described above. 


access control 
The method for determining who may reference or modify segments 
(files) and directories, or use a resource. 


access control list (ACL) 
A set of access identifiers specifying who may access a segment or 
directory. Associated with each access identifier is a set of allowed 
modes of access to that segment or directory. There is an ACL for 
each segment and each directory. 


access control segment (ACS) 
A zero length segment whose ACL is used in determining the user's 
access to a resource (see "Access Control Segments" described above). 


access isolation mechanism (AIM) 
Extension of standard access controls. AIM regulates’ the 
nondiscretionary access control features, which allow site-defined 
levels and categories of privilege. 


access modes 
A way to identify the kinds of access that may be set for a resource. 
The access modes for segments are read (r), write (w), execute (e), 
and null (n). Those for directories are status (s), modify (m), 
append (a), and null (n). 


accounting owner 
The person who uSually pays a fee for the right to control the access 
to a resource for acertain period of time (also referred to as 
owner). 


acquire 
To contract with the system to become the accounting owner of a 
resource, Acquisition is not per process; it lasts until the resource 
is explicitly released (see release). 


allocation switch 
A switch, strictly for the user's convenience, that is turned on or 
off. For example, if the resource is a tape volume, it can be used to 
indicate whether the tape contains needed data. 


assign 
To allow a process to have temporary exclusive rights to a resource 
(no one else can use it during this period of time -- no longer than 
per-process). 

attributes 


Fields that give descriptive information about devices and volumes. 
For example, a tape can have the attributes track=7 and den=1600, 
which describe the density and number of tracks on a tape. Allowable 
values for attributes are defined by the system administrator. 
Attributes can be listed by users with the resource status command and 
changed by users with the set_resource command (see Section 4). (See 
also potential attributes and protected attributes below.) 
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cancel 
To give up exclusive rights to a resource; the opposite of reserve. 


deregister 
To remove a resource from the free pool; makes it unknown to the 
system (see register). 


free pool 
The list of resources kept by resource management from which users may 
acquire resources. 


free resource 
A resource that is in the free pool. 


known 
In RCP, to register a resource is to make it known to the system (at 
that time, the resource is entered into one of the registries). 


potential attributes 
Fields that show what the resource is capable of doing. For example, 
a tape drive can have the potential attribute track=7 or track=9 but 
not both. It might also have the potential attributes den=1600 and 
den=6250 but not den=800. 


protected attributes 
Fields that designate that certain attributes of a device are 
protected from being changed. The user must have execute effective 
access to the resource to modify protected attributes. 


RCP administrator 
An administrator who can register and deregister resources. To do 
this he must have execute access to the rep admin_ gate. 


RCP effective access 
A user's access to a resource, determined by a combination of 
access-regulating methods (see "RCP Effective Access" in this 


section). 

register ; 
To introduce a resource to the system as available for acquisition; a 
registered resource remains so until explicit deregistration--this is 
not a per-process state. 

registry 
A data base maintained by and for RCP that describes all resources of 
a given type. There is a registry for each type of resource. 

release 
To give up ownership of a resource and put it back into the free pool 
(opposite of acquire). 

reserve 
To schedule with RCP the exclusive rights to a resource. 

resource 


volume used on 


A component of the system, such as a tape drive or a 
one of those peripnerais wnose use is controiied by RCP 
resource control package (RCP) 
The software, operating in ring 1, that controls the registration, 
acquisition, reservation, assignment, and use of the resources whose 
resource types are described in the RTDT. 


resource type 
A category of resources, such as tape drive or printer. 


resource type description table (RTDT) 


A binary segment describing in detail all of the resource types (e.g., 
tape drive, tape_vol) controlled by RCP. 
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resource type master file (RTMF) 
An ASCII segment compiled by the cv_rtmf command to produce the RTDT. 


ring 
A particular level of privilege at which programs may execute. 
Lower-numbered rings are of higher privilege than higher-numbered 
ones. The supervisor program runs in ring 0; most user programs runs 
in ring 4. 


ring brackets ; 
A set of integers associated with each segment that define in what 
rings that segment may be written, read, called, or executed. 


system administrator 
A highly privileged user who maintains system data bases that control 
when and by whom the system can be accessed. The system administrator 
has access to all Multics commands, has the ability to alter any 
operating parameter of the system, and may make emergency repairs. He 
is also concerned with the basic rules and prices for use of system 
resources. 


system pool 
The list of system-owned resources (such as tape drives, scratch 
volumes, and disk drives) that may be used on a public basis. 


system security administrator 
A system administrator whose primary responsibility is the integrity 
of the system and maintenance of the access control mechanisms, 
particularly AIM. 


unassign 
To give up temporary exclusive rights to an (unreserved) resource; 
opposite of assign. 


User_id 


A Person_id.Project_id pair designating ownership of a resource, for 
accounting purposes. 
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SECTION 2 


HOW TO USE RESOURCE MANAGEMENT 


As an aid to understanding how users interact with the Resource Management 
Facility, this section shows by example how a user at a sample site requests and 
manipulates tapes. Although the examples refer specifically to tapes, the 
methods generally apply to the use of other resources as well. 


View this section as an imaginary publication issued at a specific site. 
Certain capabilities, which have been marked nonstandard, have been developed by 
administrators at the site and are therefore site-specific, 


ms 


Tape Registration 


Before a tape may be used, it must be registered. An attempt to mount a 
tape that has not been registered results in an error message such as "Resource 
not known to system" or "Mount request not honored." To verify that a tape is 
registered, use the resource status (rst) command. For example, to see if tape 
EX0010 is registered, use the following command line: 


resource status tape _vol EX0010 
Acquisition Of Tapes 

To request a tape to use (i.e., to rent) use the acquire resource (aqr) 
command: 

acquire resource tape vol -number 1 


The system returns the name of a tape which is then "owned" by the user. 


To release a tape, use the release resource (rir) command: 

release resource tape _vol reel_no 

To list all tapes that have been acquired (i.e., for which you are the 
owner) use the list_resources (lr) command: 


list_resources -acquisitions -type tape vol 
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To use a tape from another computer system, you must have it registered. 
(The following describes a sample site operating policy.) Give the tape to the 
Multics operator. If you know what label is recorded on the tape, give that 
information to the operator. If you do not know what the label is, the operator 
assigns a number for the tape. You must also tell the operator your Multics 
Person_id and Project_id. The operator then registers the tape and acquires it 
to you. You receive a message when this has been done. (The sending of this 
message is a nonstandard, site-specific feature.) You can also verify that this 
has been done by listing your tapes with the list _resources command as explained 
above. You may then use the tape exactly as you would a tape that you had 
acquired with acquire resource, except that you cannot release the tape. (The 
fact that you cannot release the tape is also a nonstandard, site-specific 
item.) The same warnings apply about access. By default, only the owner can 
use the tape. When you have finished using the tape, ask the operator to 
deregister the tape (thereby removing you as the owner) and to return the tape 
to you. 


Access Control 


Note that by default, the access for a tape is "rw Person.Project", where 
Person and Project are the Person_id and Project_id of the owner of the tape. 
This means that this tape is only usable by that person, and only under that 
project. An attempt to use the tape under a different Person _id or Project_id 
results in an error message stating "Resource not accessible to requesting 
process" or "Mount request not honored." Check your access to a tape by using 
the resource status (rst) command as described above. 


To change this access, the owner of a tape can use the set resource 
command. With set_resource, specify an Access Control Segment (ACS), whose ACL 
is used as the ACL of the tape. This ACS is not created by the set_resource 
command. It must be created by the user. 


create path.acs 
set_acl path.acs mode User_id 
set resource tape vol tape -acs path path 


For example, to give user Jones access to write on a tape named CU0001 and 
allow anyone on the XYZ project to read the tape, the owner of tape CU0001 could 
use the following sequence of commands: 


create my tapes.acs 

set_acl my_tapes.acs rw Jones.* 

set_acl my_tapes.acs r *.XYZ 

set_resource tape vol CU0001 -acs path my tapes.acs 
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SECTION 3 


ADMINISTRATIVE AND USER INTERFACES 


ADMINISTRATIVE DATA BASES AND INTERFACES 


Several data bases and administrative commands are required to manage 
resources via the RCP facility. If resource management is not activated, these 
features can be ignored. However, once resource management is enabled, the RCP 
administrator must manage the data bases and perform privileged actions for the 
user community. 


The sequence of events that must occur to use a_ resource with resource 
management enabled is: 


1. The RCP administrator registers the resource using the 
register resource command, making the resource known to the system. 


Ce The user acquires the resource using the acquire resource command, 
telling the system to make him the owner and stating his willingness 
to pay for the resource (this can also be done by the administrator 
for the user). 


36 Now the resource may be used by any user with appropriate access. 


A variety of information is stored by the system as part of resource 
management. This information is under the control of the RCP administrator. 
This includes all of the information in the resource type description table 
(RTDT) and most information in the registries. The RTDT, which is generated by 
the RCP administrator, defines ali of the resource types known by the system. 
Also defined in the RTDT are default values for the potential attributes, the 
potential access class range, and the charge type to be used in billing for 
resources of a given type. The registries contain information specified by the 
administrator at registration time or when a resource is acquired for a user. 
The RTDT and the registries are described in detail in the MAM RCP. 


USER INTERFACES 


Once the RCP administrator has registered a resource, a user may acquire it 
(if it is not already acquired), or, the administrator can do this acquisition 
for a user. Acquisition tells the system that the user is willing to pay for 
the resource(s) specified--for example, a tape volume. For more information on 
acquisition, see the acquire_resource command in Section 4. 
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Once a resource has been acquired it can be used (reserved, assigned, and 
attached) by any user with appropriate access. This means the user is on the 
ACL of the ACS, is at the proper validation level, and is within the access 
class range for this resource specified by the administrator. (See "Access 
Control Segments" in Section 1.) 


It is important to realize that there is normally no implicit acquisition, 
and that only acquired resources can be used. The only exception to these rules 
occurs when a site has "automatic registration" turned on during the initial 
time period after enabling the full resource management facility. While 
automatic registration is on, any unregistered tape volume for’ which the 
operator honors a mount request is automatically registered and acquired to the 
requesting user. 


Naming Rules for Attributes 


Attributes provide a description of a volume or device that assists the 
resource management facility in the proper matching of volumes with compatible 
devices. To produce correct combinations, attribute names must comply with the 
set of rules described below. 


Attributes may be grouped or ungrouped. Grouped attributes specify a set 
of properties applicable to a device or volume such that only one attribute of 
that set can be currently active at any given time. For example, a reel of tape 
may have potential attributes that allow it to be recorded at densities of 556, 
800, or 1600; however, at any given time, the data on it is in only one of those 
densities. Grouped attributes have names of the form: 


<identifier>=<value> 


For example, the attributes mentioned above are named "den=556", "den=800", and 
"den=1600",. This notation allows RCP to recognize that any request to make one 
of these attributes the current attribute of a device or volume also implies 
that all other attributes in that grouping must be made inactive. 


Ungrouped attributes have simple names, such as "trainok" (to specify that 
this device accepts a removable print train) or "building 12" (to specify that 
this device or volume is located in building 12). 


User Manipulation of Registries 


The user of a resource has’ limited control over the information maintained 
by the system describing the resource. Most of this information is 
specified/modified via the acquire resource and set_resource commands. When a 
user acquires a resource (using the acquire resource command), he can specify 
the ACS pathname, current attributes, comment, and user allocation state of the 
resource uSing the -acs path, -attributes, -comment, and -alloc control 
arguments. At any time between acquisition and release, this information can be 
manipulated using the set_resource command-= and displayed using the 
resource status command/active function. See Section 4 for descriptions of 
these commands. 
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Any user with write RCP effective access to the resource can modify the 
current attributes, comment, or user allocation state. In addition, only 
resource executives (execute RCP effective access to the resource) can modify 
protected attributes. Finally, only the owner of the resource can modify the 
ACS pathname maintained by resource management. 


However, RCP administrators, by virtue of their privilege, can effectively 


modify all the information described, for any resource, plus other information 
ot described here (see the MAM RCP for details). 


rs 


o 


Ma 1101 
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SECTION 4 


USER COMMANDS 


This section contains descriptions of the user commands that acquire 
resources, list all resource types described in the RTDT, release resources, 
print a description of the status of a resource, and modify the parameters of a 
resource, Each description contains the name of the command (including the 
abbreviated form, if any), discusses the purpose of the command, and shows the 
correct usage. Notes and examples are included when deemed necessary for 
clarity. The discussion below briefly describes the content of the various 
divisions of the command descriptions. 


Name 


The "Name" heading lists the full command name and its abbreviated form. 
The name is usually followed by a discussion of the purpose and function of the 
command and the expected results from the invocation. 


Usage 


This part of the command description first shows a single line that 
demonstrates the proper format to use when invoking the command and then 
explains each element in the line. The following conventions apply in the usage 
line. 


i Optional arguments are enclosed in braces (e.g., {path}, {User_ids}). 
All other arguments are required. 


ae Control arguments are identified in the usage line with a leading 
hyphen (e.g., {-control_args}) simply as a reminder that all control 
arguments must be preceded by a hyphen in the actual invocation of the 
command. 


3% To indicate that acommand accepts more than one of a specific 
argument, an "s" is added to the argument name (e.g., paths, {paths}, 
{-control_args}). 


NOTE: Keep in mind the difference between a plural argument name that is 
enciosed in braces (i.e€., optional) and one that is not (i.ée., 
required). If the plural argument is enclosed in braces, clearly no 
argument of that type need be given. However, if there are no 
braces, at least one argument of that type must be given. Thus 
"paths" in a usage line could also be written as: 


path1 {path2 ... pathn} 


The convention of using "paths" rather than the above is merely a 
method of saving space. 
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4, Different arguments that must be given in pairs are numbered (e.g., 


xxx1 yyyl {... xxxn yyyn}). 


Ss To indicate that the same generic argument must be given in pairs, the 


arguments are given letters and 


(e.g., pathAl pathBi1 {... pathAn pathBn}). 


6% To indicate one of a group of the same arguments, an "i" 


the argument name (e.g., pathi, User_idi). 


To illustrate these conventions, consider the following usage line: 


command {paths} {-control_args} 


numbers 


is added to 


The lines below are just a few examples of valid invocations of this command: 


command 

command path path 

command path -control_ arg 

command -control_ arg -control arg 

command path path path -control_arg -control_arg -control_arg 


In many cases, the control arguments take values. For simplicity, common 


values are indicated as follows: 


STR any character string; individual command descriptions indicate 
any restrictions (e.g., must be chosen from specified list; must 


be either the string on or the string off). 


N number; individual command descriptions indicate 


octal or decimal and any other restrictions (e.g., 


greater than 4). 


DT date-time character string in a form acceptable 
convert _date to binary subroutine described 
Subroutines. 

path pathname of an entry;. unless otherwise indicated, 


either a relative or an absolute pathname. 
The lines below are samples of control arguments that take values: 
~access name STR, -an STR 
-ring N, -rg N 


-date DT, -dt DT 
-home dir path, -hd path 


Notes 


whether it is 
cannot ve 


to the 


the MPM 


it may be 


Comments or clarifications that relate to the command as a whole are given 
under the "Notes" heading. Also, where applicable, the required access modes, 


the default condition (invoking the command without any arguments), 


Special case information are included. 
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Examples 


The examples show different valid invocations of the command. An 
exclamation mark (!) is printed at the beginning of each user-typed line. This 
is done only to distinguish user-typed lines from system-typed lines. The 
results of each example command line are either shown or explained. 


Other Headings 


Additional headings are used in some descriptions, particularly the more 
lengthy ones, to introduce specific subject matter. These additional headings 
may appear in place of, or in addition to, the notes. 
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acquire_resource acquire resource 


Name: acquire_resource, aqr 


The acquire resource command selects a resource of a given type from a free 
pool of all such resources, and makes the user the accounting owner of the 
resource. The accounting owner is given full control over the access rights of 
all users of the resource, as well as control over many parameters of the 
resource. Ownership of the resource is terminated via the release resource 
command. 


Usage 


acquire _resource type STR1 {... STRn} {-control_args} 
or 
aqr type -number N {-control_args} 


where: 

1. type 
is a resource type defined in the RTDT. 

2. STRi 
is the unique identifying name of the particular resource being 
acquired. If STR looks like a control argument (i.e., if it is 
preceded by a hyphen), then it must be preceded by -name or -nm. If 
name is not supplied, -number must be given, anda resource is 
chosen to satisfy the constraints imposed by the control arguments 
given. 

3. control _ args 


can be chosen from the following: 


-access class accr, -acc acer 
sets the initial AIM access class parameters where accr is an access 
class range. Users at any authorization within the access class 
range inclusive are allowed to read and write to the resource 
(provided they also meet other access requirements). For a detailed 
description see "Access Class Ranges" in Section 1. 


-acs_ path path 
specifies the pathname of the access control segment (ACS) for this 
resource. The ACS is not created by this command, but must be 
created by the owner, and the desired access control iist set. if 
the ACS does not exist or is not specified, the default access is 
rew to the accounting owner, and null to all others. 


-alloc STR 
sets the allocation state of the resource to free or allocated, 
where STR must’ be either the string on or the string off. If this 
control argument is not given, the allocation state is free. (The 
allocation state flag is a convenience to the user and is largely 
ignored by resource management.) 
on sets the allocation state to allocated 
off sets the allocation state to free 
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acquire resource acquire resource 


-attributes STR, -attr STR 
specifies that the resource chosen must possess’ the potential 
attributes specified in STR. When a_ satisfactory resource is 
located, the current attributes are set to a proper combination of 
these attributes (see "Notes" below). 


-comment STR, -com STR” ; 
specifies the desired value of the comment string for this resource. 


-lock STR 
locks or unlocks the resource, preventing or allowing use of that 
resource, where STR must be either the string on or the string off. 
If this control argument is not specified, the lock is off. 
on prevents any use of the resource 
off allows use of the resource 


-number N, -nb N 
specifies that the number of such resources to be acquired is N. If 
this control argument is not given, 1 is assumed. This control 
argument may only be specified if the STR argument is not given (see 
"Usage" above). 


-owner STR, -ow STR 

specifies that this is an acquisition on behalf of the user 
specified by STR. If STR is the string "system", then the resource 
is acquired to the system pool. If STR is the string "free", then 
the resource is left in the free pool (effectively the same as no 
-owner). If STR is of the form Person _id.Project_id (where neither 
Person_id nor Project _id may be a star), the user specified has all 
the rights of ownership to the resource as if he had acquired it 
personally, except that if "-release_lock on" is specified, the 
owner may not release (give up ownership of) the resource 
voluntarily. 


-release_ lock STR, -rll STR 

specifies whether this resource may be released by the owner, or may 
only be released by a privileged process (see "Access Restrictions" 
below), where STR must be either the string on or the string off. 
If this control argument is not specified or is the string off, the 
resource may be released by the owner. 

on resource may only be released by privileged process 

off resource may be released by owner 
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acquire resource acquire _resource 


Notes 


This command acquires a resource for either the user issuing it (requestor) 
or the user specified by the -owner control argument. If the requestor is 
registered on more than one project and needs corresponding access, or other 
users (on any project) need access to use a resource, the owner must create or 
modify an access control segment (ACS). The owner must then specify the 
new/modified ACS using the -acs_path control argument either when issuing this 
command or later with the set_resource command. 


For a description of the syntax of attribute strings, see "Naming Rules for 
Attributes" Section 3. 


The use of this command for attaining the desired RCP effective access is 
explained under "Access Control Segments" in Section 1. 


Access Restrictions 


The use of the -owner, -release_ lock, or -access_ class control arguments 
requires execute access to the rcp_admin_ gate. 
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assign_resource assign resource 


Name: assign resource, ar 


The assign resource command calls the resource control package (RCP) to 
assign a resource to the user's process. 


Usage 


ar resource type {-control_args} 
where: 


Vs resource type 

specifies the type of resource to be assigned. Currently, only 
device types can be specified. The -device control argument is used 
to name a specifie device to assign. Other control arguments are 
used to specify characteristics of the device to be assigned. The 
following device type keywords are supported: 

tape_drive 

disk drive 

console 

printer 

punch 

reader 

special 


2. control_args 
can be chosen from the following: 


specifies the name of the device to be assigned. If this control 
argument is specified, other control arguments that specify device 
characteristics are ignored. (See "Examples" below.) If the -long 
control argument (see below) is used in conjunction with this 
control argument, a message containing the name of the assigned 
device is printed. on the user's terminal; otherwise, no message is 
printed. 


-model N 
specifies the device model number characteristic. Only a device 
that has this model number is assigned. In order to find the model 
numbers that are acceptable, use the print _configuration_deck 
command described in System Tools, Order No. AZ03. 


-track N, -tk N 
specifies the track characteristic of a tape drive. The value can 
he either 9 or 7. If this control argument is not specified and if 
the -volume control argument is not specified, a track value of 9 is 
used when assigning a tape device. 
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-density N, -den N 

specifies the density capability characteristic of a tape drive. 
There can be more than one instance of this argument. A tape drive 
is assigned that is capable of being set to all of the specified 
densities. The acceptable values for this argument are: 

200 

556 

800 

1600 

6250 


Note that the values permitted depend on the particular hardware on 
the system. 


-train N, -tn N 
specifies the print train characteristic of a printer. 


-line length N, -11 N 
specifies the line length of a printer. Its value must be one that 
is found in the "line length" field of a printer PRPH configuration 


ecard. if this field is not specified on a printer PRPH 
configuration card, this device characteristic is ignored for this 
printer. 


-volume STR, -vol STR 
specifies the name of a volume. If possible, the device assigned is 
one on which this volume has already been placed. If this is not 
possible (e.g., the volume is on a device assigned to a process) any 
available, appropriate, and accessible device will be assigned. 


-number N, -nb N 
specifies the number of resources to assign. All of the resources 
assigned have the device characteristics specified by any other 
-arguments passed to this command. If this control argument is not 
specified, one resource is assigned. 


-comment STR, -com STR 
is a comment string that is displayed to the operator when the 


resource is assigned. If more than one string is required, the 
entire string must be in quotes. Only printable ASCII characters 
are allowed. Any unprintable characters (also tabs or new lines) 


found in this string are converted to blanks. 


-~long, -lg 
specifies that all of the device characteristics of the assigned 
device should be printed. If this argument is not supplied, only 
the name of the assigned device is printed. 


-system, -sys 
specifies that the user wants to be treated as a system process 
during this assignment. If this argument is not specified or if the 
user does not have the appropriate access, then the RCP assumes that 
this assignment is for a nonsystem process. 


-wait {N}, -wt iN} 
specifies that the user wants to wait if the assignment cannot be 
made at this time because the resources are assigned to some other 
process. The value N specifies the maximum number of minutes to 
wait. If N minutes elapse and a resource is not yet assigned, an 
error message is printed. If N is not specified, it is assumed that 
the user wants to wait indefinitely. 
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-speed N 
specifies the speed of a tape drive. The acceptable values depend 
on the particular hardware on the system and can be the following: 
75 
125 
200 


Notes 


Currently, only device resources can be assigned. An assigned device still 
must be attached by a call to some I/O module. If a device is successfully 
assigned, the name of the device is printed. (If the user requests a specific 
device that is successfully assigned, the name of the device is not printed 
unless the user asks for it. See the -device and -long control arguments 
above.) 


Examples 


In the example below, the user issues the assign resource command with the 
"Cape drive" keyword and the -model control argument. The system responds with 
the name of the assigned device. 

! assign resource tape drive -model 500 

Device tape 04 assigned 
In the next example, the user issues the assign resource command with the 
"Cape drive" keyword and the -device and -long control arguments.. The system 
responds with the name of the assigned device and the model number, track, 
density and speed characteristics. 


! assign_resource tape drive -device tape _05 -long 


Device tape 05 assigned 


Model = 500 

Tracks = 9 

Densities = 200 556 800 1600 
Speed = “F265 
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Name: cancel _ resource, cnr 


The cancel resource command cancels reservations made with the 
reserve _ resource command using the reservation identifier obtainable from the 
list resources command. 


Usage 


enr -id reservation_id {-control_arg} 


where: 
1. reservation_id 
must be present and is the reservation identifier of the reservation 
to be cancelled. It must be preceded by the -id control argument. 
2. control _ arg 
ean be -priv to specify the privileged cancellation of a reservation 
belonging to another user (see "Access Restrictions" below). 
Notes 


Reservation identifiers can be obtained by using the list_resources 
command. 


Access Restrictions 


Use of the -priv control argument requires access to rep_sys_. 
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Name: list _resource_types, I1rt 


The list_resource_types command prints a list of all resource types 
deseribed in an RTDT. 


Usage 


list_resource types {typel ... typen} {-control_args} 


where: 

1. typei 
is the resource type defined in the RTDT for which information is to 
be listed. If no type is specified, all known resource types are 
listed. 

2. control args 


ean be chosen from the following: 


-long, -lg 
lists the defined attributes for each resource type. 


~no_header, -nhe 
omits the column headers. 


-pathname path, -pn path 
lists resource types de ed in the RTDT specified by path. If this 
control argument is not specified, the RTDT residing in 
>system_control_1 is us 
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Name: list _resources, Ir 


The list _resources command lists groups of resources managed 


by the 


Resource Control Package (RCP), selected according to criteria specified by the 


user. 


Usage 


lr {-control_args} 
or 
[lr {-control_args}] 
where control _args can be chosen from the following: 


-acquisitions, -acq 


lists resources acquired by the user specified by the -user control 


argument. If this control argument is used, -type must 
specified. 


~assignments, -asm 


also be 


lists resource assignments. This cannot be used with the active 


function. 

-awaiting clear 
lists those resources that are awaiting manual clearing. 
control argument is used, -type must also be specified. 


-device STR, -dv STR 


If this 


lists device resources with the name STR. No other resources are 


listed. This cannot be used with the active function. 


-logical_ volume, -lv 


lists logical volumes that are currently attached. This cannot be 


used with the active function. 


-long, -lg 


prints all the information known about each resource listed. 


If 


this control argument is not supplied, only the name is printed for 
each resource listed. This cannot be used with the active function. 
-lg has no effect if the -acq control argument has been specified. 


-mounts, -mts 


lists resources currently mounted by the process. This cannot be 


used with the active function. 


-reservations, -resv 


lists only device and volume reservations. This cannot be used with 


the active function. 


-type STR, -tp STR 


lists resources of the type STR. See list resource types for 


information on obtaining the names of resource types. 
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-user User_id 
selects a particular user or group of u 
information is to be printed. This contr 
only in conjunction with -acquisitions. Th 
the following forms: 


ers for whom resource 


Ss 
ol: argument can be used 
e User_id can be any of 


Person. Project 
specifies a particular Person_id and Project_id combination. 


*.Project 
specifies all users on a specified project. 


specifies all users (i.e., all acquired resources of the given 
type are listed). 


free 
specifies all resources of the given type in the free pool. 


system 
specifies all resources of the given type in the system pool. 


%% 
specifies all users plus the free and system pools (i-.e., all 
registered resources of the given type will be listed). 


If this control argument is not specified, the User_id of the user 
invoking list_resources is assumed. If this control argument is 
used, -type must also be _ specified. See "Notes on Access 
Restrictions" below. 


Notes 


If this command is invoked without any arguments, all resources assigned 
and devices attached to the calling process are listed. 


Access to rep_admin_ is required to obtain information on other users! 
resources. Read access to the PDT (Project Definition Table) of a specified 
project is required to obtain information for that project. 


Examples 


In the exailpie WwW, tne user i es the list re 
ystem responds with the name of 


ve 

control arguments. The 
» clip 

Device Assignments 


Device tape _05 
Device tape_02 


In the next example, the user issues the list_resources command with the 
-long control argument. The system responds with all the information known 
about each resource listed. 
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list_resources 


! 


lr -lg 


Device Assignments 
2 devices assigned 
Device tape_05 
State 
Time 
Disp 
Level 
Model 
Tracks 
Densities 
Speed 
Device tape | 
State 
Time 
Disp 
Level 
Model 
Tracks 
Densities 
Speed 


Hun wb tb ob tt Ot tt WoW Ho tb 
NM 


assigned 
04/30/76 1316.2 edt Fri 
retain 


500 


9 
200 556 800 1600 
125 


assigned 

04/30/76 1314.7 edt Fri 
retain 

4 

500 


9 
200 556 800 1600 
125 


list resources 


In the following example list_resources is invoked to obtain a list of tape 
volumes for which the user is the accounting owner. 


! 


lr -tp tape_vol -acq 


4 resources of type tape_vol acquired by Dahl.GNP 


at 05/10/79 2025. 


a-153 
a-022 
u-405 
a-558 


5 mst Thu: 
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Name: release_resource, rir 


The release_resource command releases a resource into the free pool. A 
resource may only be released by its accounting owner or an RCP administrator. 


Usage 


release resource type STR1 ... STRn {-control_arg} 


where: 
1. type 

is a resource type defined in the RTDT. 
Zs STRi 


is the unique identifying name of the particular resource being 
released. If STR looks like a control argument (i.e., if it is 
preceded by a hyphen), then it must be preceded by -name or -nm. 


3. control _ arg 
can be -priv to specify that the user wishes to perform a privileged 
release of this resource from the accounting owner, even though the 
user may not be the accounting owner (see "Access Restrictions" 
below). 


Access Restrictions 


The use of the -priv control argument requires execute access to the 
rep_admin_ gate. 
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reserve _ resource reserve resource 


Name: reserve_resource, rsr 


The reserve_resource command reserves a resource or group of resources for 
use by the calling process. The reservation takes effect immediately and lasts 
until cancelled by the cancel resource command or by process termination. The 
user pays for reserved time as if the resource were attached. 


Usage 


rsr -control_arg 
where control _arg is -resource STR, -rse STR, to specify a description of the 
resources to be reserved. If this resource description contains spaces or 


special characters, it must be enclosed in quotes. This resource description 
can also have control arguments and is described in more complete detail below. 


Notes on Resource Description 
A resource description describes certain devices and volumes by name or by 
attributes and an optional number. It has the following format: 
{-resource_type} resource_speci ... {-resource_type resource_specn} 
That is, a series of at least one resource _ spec where all but the first must be 
preceded by the -resource type or -rsct controi argument. The first need not be 
preceded by the control argument. 
The format of a resource _spec is as follows: 
volume _type name1 {names} 
or: 
device type {names} 
or: 
device type {-control_args} 
where: 
1. volume type 
can be either tape_vol or disk vol. At least one name must be 
specified with volume_type, and it is the name of the volume, for 
example, 050102. 
2% device_type 
can be either tape_drive or disk_drive. Names are the names of 
devices such as tape 01, and if names are specified with a 
device type, no control arguments are allowed. Names are not 
required, therefore a device type can be specified with no names or 


control arguments. If names are not specified, the control_args for 
use with device type can be chosen from the following: 
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-attributes STR, -attr STR 
the attribute string STR consists of a string of attributes with 
values separated by commas with no spaces. For tape drives the 
attributes are: 
mode= ~ 
track= 
den= 
For disk drives the only attribute is: 
model= 


Suitable values for these attributes can be found by using the 
list_resource types command also in this manual. 


-number N, -nb N 
is the number of identical resources of the type desired. 


Examples 


rsr -rse "tape_vol 50102 u-309 -rset tape drive -attr 
track=9,den=800 -nb 2" 


This command line reserves four resources: two tapes, 050102 and u-309; two 
tape drives, both being 9-track and capable of 800 bpi operation. 
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resource status resource status 


Name: resource status, rst 


The resource status command prints selected information about the status of 
a given resource. This command can also be invoked as an active function (see 
"Notes" below). 


Usage 


resource status type STR1 ... STRn i-control_args} 
or 
[resource status type STR -control_arg] 


where: 

1. type 
is a resource type defined in the RTDT. 

ee STRi 
is the unique identifying name of the particular resource desired. 
If STR looks like a control argument (i.e., if it is preceded by a 
hyphen), then it must be preceded by -name or -nm. 

36 control args 


can be chosen from the following: 


-access class, -acc 
prints the AIM access class or access class range of the resource 
(see "Notes" below). 


-acs_ path 
prints the pathname of the ACS for this resource (see "Notes" 
below). 


-all, -a 
specifies that all information maintained about this resource is to 
be printed. This control argument is not allowed in an active 
function invocation. 


-alloce 
specifies that the state of the user allocation switch for this 
resource is to be printed. 


-attributes, -attr 
prints the current and protected attributes of this resource. 


-comment, -com 
prints the user-settable comment associated with this resource. 


-location, -loc 
prints the location field associated with this resource. 


-lock 
prints the status of the resource lock for this resource. In an 
active function invocation, "true" is returned if the lock is on; 
"false" is returned if it is off. 
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-mode, -md 
prints the user's RCP effective access mode to the resource. 


-owner, -OW 
prints the name of the owner of the resource. 


-potential access _class, -pacc 
prints the potential access class or potential access class range 
for this resource (see "Notes" below). 


-potential attributes, -pattr 
prints the potential attributes of this resource. 


-priv 
specifies that a privileged call is to be made to obtain the status 
of this resource (see “Access Restrictions" below). 


~release lock, -rll 
prints the status of the lock which prevents the owner from 
releasing this resource. In an active function invocation, "true" 
is returned if the lock prevents the owner from releasing the 
resource; "false" is returned otherwise. 


-uid 
prints the unique identifier of this resource. 


Notes 


If no control arguments are given, some fields are printed by default. The 
information about the specified resource that this command prints by default is 
the name of the owner, the current and protected attributes, the user's RCP 
effective access mode, the pathname of the ACS, the user_settable comment, and 


the state of the user allocation switch for the specified resource. 


When invoked as an active function, this command returns’ the value 
requested by the specified control argument (only one control argument may be 
specified in this usage). (Active functions are fully described in Section 2 of 
the MPM Commands.) 


Access Restrictions 


The use of the -priv control argument reauires execute access to the 
rep_admin_ gate. 
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Name: set _resource, setr 


The set_resource command is used to modify parameters of a resource. 


Usage 


set_resource type STR1 ... STRn -control_args{s} 


where: 

de type 
is a resource type defined in the RTDT. 

2. STRi 
is the unique identifying name of the particular resource being 
modified. If STR looks like a control argument (i.e., if it is 
preceded by a hyphen), then it must be preceded by -name or -nm. 

3. control _ args 


ean be chosen from and must include at least one of the following: 


-access_ class acer, -ace acer 
sets the initial AIM access class parameters, where accr is the 
access class range. Users at any authorization within the access 
class range inclusive are allowed to read and write to the resource 
(provided they also meet other access requirements). For a detailed 
description see "Access Class Ranges" in Section 1. 


-acs_ path path 

specifies the pathname of the access control segment (ACS) for this 
resource. The ACS is not created by this command, but must be 
created by the accounting owner, and the desired access control list 
set (see "Notes" below). If this control argument is not given, the 
accounting owner of the resource is given rew access by default. If 
path is a null string, the existing ACS, if any, is disassociated 
from the resource. 


-alloec STR 
sets the allocation state of the resource to free or allocated, 
where STR must be either the string on or the string off. If this 
control argument is not given, the allocation state is free. (The 
allocation state flag is a convenience to the user and is largely 
ignored by resource management.) 
on sets the allocation state to allocated 
off sets the allocation state to free 


-attributes STR, -attr STR 
specifies the desired values for the attributes of this resource 
(see "Notes" below). 


-comment STR, -com STR 
specifies the desired value of the comment string for this resource. 


-location STR, -loc STR 
specifies a descriptive location for the resource, to aid the 
operator in locating it when it is stored in a special place (e.g., 
a vault, a different room, etc.). 
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-lock STR 

locks or uniocks the resource, preventing or allowing use of that 
resource, where STR must be either the string on or the string off. 
If this control argument is not specified, the lock is off. 
on prevents any use of the resource 
off allows use of the resource 


-release_ lock STR, -rll STR 
specifies whether this resource may be released by the owner, or may 
only be released by a privileged process (see "Access Restrictions" 
below). If this control argument is not specified or is off, the 
resource may be released by the owner (does not require special 
privilege). 
on resource may only be released by privileged process 
off resource may be released by owner 


Notes 


If multiple resources are specified to the set _resource command and an 
error oceurs in the modification of one of these resources, none of the 
resources specified are modified. 


For a description of the syntax of attribute strings, see "Naming Rules for 
Attributes" in Section 3. 


Access Restrictions 


The user must have write RCP effective access to the resource named to 
perform any modification on the status of the resource. In addition, the user 
Must have execute effective access to the resource named to modify protected 
attributes (described in Section 1). Only the accounting owner may modify the 
ACS path. The user must have execute access to the rep _admin_ gate in order to 
use the -access_ class, -release_ lock, -location, -charge type, or -lock control 
arguments. 


Certain specifications of AIM access class parameters (e.g., an access 
class lower than the user's current authorization) are rejected unless the user 
has the AIM rep privilege. , 
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unassign resource unassign_ resource 


Name: unassign_resource, ur 


The unassign resource command unassigns one or more resources that have been 


assigned to the user's process by the Resource Control Package (RCP). 


Usage 


ur resources {-control_args} 


where: 
1. resources 
specify the resources to be unassigned from the user's process. 
Currently, the only resources managed by RCP are devices. If a 
device is attached, it is automatically detached. user can 
unassign all devices assigned to the process by specifying the -all 
control argument, or unassign one device by specifying its name. 
2. control args 
can be chosen from the following: 
-comment STR, -com STR 
is a comment string that is displayed to the operator when the 
resource is unassigned. This comment is displayed only once, even 
if several resources are being unassigned. (See the assign resource 
command for details about comment strings.) 
-admin, -am 
forces an unassignment. This control argument’ should be specified 
by highly privileged users who want to unassign a resource that is 
assigned to some other process. 
-all, -a 
unassigns all devices assigned to the process. 
Examples 


In the example that follows, the user unassigns a tape previously assigned 


by the assign resource command by typing the command iine: 


! ur tape _03 
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SECTION 5 


USER SUBROUTINES 


This section contains descriptions of Multics subroutines, presented in 
alphabetical order. Fach description -contains the name of the subroutine, 
discusses the purpose of the subroutine, lists the entry points, and describes 
the correct usage for each entry point. Notes and examples are ineluded when 
deemed necessary for clarity. The discussion below briefly describes the 
context of the various divisions of the subroutine descriptions. 


Name 


The "Name" heading shows the acceptable name by which the subroutine is 
called. The name is usually followed by a discussion of the purpose and 
function of the subroutine and the results that may be expected from calling it. 


Entry 


Each "Entry" heading lists an entry point of the subroutine call. This 
heading may or may not appear in a subroutine description; its use is entirely 


dependent upon the purpose and function of the individual subroutine. 


Usage 


This part of the subroutine description first shows the proper format to 
use when calling the subroutine and then explains each element of the call. 
Generally, the format is shown in two parts: a declare statement that gives the 
arguments in PL/I notation and a call line that gives an example of correct 
usage. Each argument of the call line is then explained. Arguments can be 
assumed to be required unless otherwise specified. Arguments that must be 
defined before calling the subroutine are identified as Input; those arguments 
defined by the subroutine are identified as Output. 


Notes 


Comments or clarifications that relate to the subroutine as a whole (or to 
an entry point) are given under the "Notes" heading. 
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Other Headings 


Additional headings are used in some descriptions, particularly the more 
lengthy ones, to introduce specific subject matter. These additional headings 
may appear in place of, or in addition to, the notes. 


Status Codes 


The standard status codes returned by the subroutines are further 
identified, when appropriate, as either storage system or I/O system. For 
convenience, the most often encountered codes are listed in Appendix B of the 
MPM Subroutines. They are divided into three categories: storage system, I/0 
system, and other. Certain codes have been included in the individual 
subroutine description if they have a special meaning in the context of that 
subroutine. The reader should not assume that the code(s) given in a particular 
subroutine description are the only ones that can be returned. 


5-2 CT38-00 


ev_rep_attributes_ ev_rep attributes _ 


Name: ev_rep _attributes_ 


The ev_rep_attributes_ subroutine contains several entry points that are 
useful in manipulating RCP resource attribute specifications and descriptions. 


RCP resource attribute descriptions are printable strings that describe the 
attributes of resources (devices and volumes). For a description of the syntax 
of attribute descriptions see the Multics Administrators' Manual Project, 
Order No. AK51. 


RCP resource attribute specifications are encoded representations of 
attribute descriptions. They may be either absolute, relative, or multiple. An 
absolute attribute specification represents a complete and consistent state of 
all the attributes of a resource. A relative attribute description represents a 
desired modification to the state of all the attributes of a resource, and must 
be applied to an absolute attribute specification to produce the desired change 
in that absolute specification. A multiple attribute specification does not 
represent a consistent state of all the attributes of a resource at any given 
time, but is useful for representing the union of all such consistent states, 
i.e., potential attributes. 


Entry: ecv_rep attributes $to_string 


This entry point takes an RCP resource attribute specification and produces 
a printable RCP attribute description. 


Usage 


declare ecv_rep attributes $to_ string entry (char (*), bit (72) 


dimension (2), char (*) varying, fixed bin (35)3; 


call ev_rep attributes $to string (type, attributes, string, code); 


where: 
1 type (Input) 
specifies the type of resource from which attributes was obtained 
e.g-., disk_drive (see "Notes" below). 
2. attributes (Input) 
is an RCP attribute specification (see "Notes" below). 
3 string (Out put ) 
is a printable RCP attribute description. 
i. code (Out put ) 


is a standard status code. 
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Notes 

A list of defined resource types may be obtained via the 
list_resource types command. 
Entry: evirep attributes $from_string 


This entry point accepts a printable RCP attribute description and produces 
an RCP attribute specification. 


Usage 


declare cv_rep_ attributes $from_string entry (char (*), bit (72) 
dimension (2), char (*) varying, fixed bin (35)); 


call ev_rep_attributes $from_string (type, attributes, string, code); 


where: 
Tis type (Input) 
specifies the type of resource to which attributes applies. 
2. attributes (Output) 
is the same as above. 
3. string (Input) 
is the same as above. 
4, code (Output ) 


is the same as above. 


Entry: cv_rep_ attributes $modify 


This entry point applies a printable RCP resource attribute description 
(representing a relative attribute specification) to a given resource 
specification and returns anew attribute specification as the result. The 
resulting attribute specification consists of the original attribute 
specification, modified by the attributes specified in the printable 
description. 
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Usage 


declare ev_rep attributes $modify entry (char (¥*), bit (72) dimension (2), 
char (*) varying, bit (72) dimension (2), fixed bin C3525 


call ev_rep_ attributes $modify (type, attributes, string, new caterinuted, 


code); 
where: 
Ve type (Input) 
specifies the type of resource to which attributes and string apply. 
2 attributes (Input) 
is an absolute RCP attribute specification. 
3. string (Input) 
is a printable RCP attribute description that is to modify 
attributes. 
4, new_attributes (Out put ) 
is the new absolute RCP attribute specification. 
Ba code (Output ) 


is the same as above. 


Entry: ev_rep attributes $from_string rel 


This entry point generates a relative attribute specification that can later 
be applied to attribute specifications of specific resources via the 
ev_rep attributes $modify_rel entry point. 


Usage 


declare cv_rep attributes $from_string rel entry (char (*), 
char (*) varying, bit (72) dimension (4), fixed bin (35))3 


eall ev_rep attributes $from_string rel (type, string, rel_attributes, 
code); 
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where: 
1. type (Input) 
specifies the type of resource to which string applies. 
2. string (Input) 
is a printable RCP attribute description. 
3. rel_attributes (Output ) 
is the relative RCP attribute specification. 
4, code (Out put ) 


is the same as above. 


Entry: ev_rep_attributes $modify_rel 


This entry point applies a relative attribute specification produced by the 
ev_rep attributes $from_string rel entry point to an absolute attribute 
specification of a specific resource. 


Usage 


declare ev_rep attributes $modify rel entry (bit (72) dimension (2), 
bit (72) dimension (4), bit (72) dimension (2)); 


eall ev_rep attributes $modify_rel (attributes, rel_attributes, 
new attributes); 


where: 
se attributes (Input) 
is an absolute attribute specification. 
2. rel attributes (Input) 
is a relative attribute specification to be applied to attributes. 
3. new_attributes (Output ) 
is the resulting absolute attribute specification. 
Notes 


The caller must ensure that attributes and rel_attributes refer to the same 
resource type, i.e., were generated by previous calls to ev_rep attributes _ 
where the type arguments were identical. 
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Entry: ev_rep_attributes $reduce_ implications 


This entry point accepts an attribute specification for a volume and 
returns the necessary minimal attribute specification that a device must possess 
to be able to accept the volume. 


declare ev_rep attributes $reduce_implications entry (char (*), bit (72) 
dimension(2), char (*), bit (72) dimension (4), fixed bin (35)); 


call ev_rep attributes $reduce_implications (vol_type, vol_attributes, 
dev_type, dev_attributes, code); 


where: 
Ts vol_type (Input) 
specifies the type of volume from which vol_attributes was obtained. 
2. vol_attributes (Input) 
is an absolute attribute specification for the volume type 
specified. 
cre dev_type (Output) 
is the resource type of the device that accepts the given volume 
type. 
4, dev_attributes (Output) 
is a minimal relative attribute specification for a device capable 
of accepting a volume with the given attributes. 
5. code (Output ) 


is the same as above. 


Entry: ev_rep_attributes $protected_ change 


This function entry point accepts an absolute attribute specification for a 
resource ana a réiative attribute specification which is to modify it. it 
returns a value expressing whether or not this modification would affect 
protected attributes of the resource. No modification is actually attempted by 
this entry. 
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Usage 
declare cv_rep attributes $protected change entry (bit (72) dimension(2), 
bit (72) dimension(4)) returns (bit (1) aligned); 


protected_change = ecv_rep attributes $protected_ change (attributes, 
rel_attributes) ; 


where: 
1 attributes (Input) 
is an RCP attribute specification. 
2. rel_ attributes (Input) 
is a relative attribute specification to be applied to attributes. 
ce protected change (Out put ) 


is "1"b if this operation would modify protected attributes of the 


resources; otherwise, it is "O"b. 


Entry: ecv_rep_ attributes $test_valid 


This entry point is used to determine whether a given attribute 
specification is absolute, relative, multiple, or invalid. 


Usage 


declare ecv_rep_attributes $test_valid entry (char(*), bit 72 dimension (2), 
fixed bin, fixed bin (35)); 


call ev_rep attributes $test_valid (type, attributes, validity, code); 


where: 
1s type (Input) 
specifies the type of resource to which attributes applies. 
25 attributes (Input) 
is an RCP attribute specification. 
3. validity (Out put ) 
shows whether the attribute specification is absolute, relative, or 
multiple. 
0 is an absolute attribute specification 
1 is a relative attribute specification 
2 is a multiple attribute specification 
4. code (Out put ) 


is a standard status code. 
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Name: resource_control_ 


The resource_control_ subroutine provides an interface to the Multics 
resource control facility. Entry points in this subroutine allow programs to 
reserve or cancel I/O devices and volumes. 


Entry: resource control _ $reserve 


This entry point reserves a resource or group of resources for use by a 
process. 


Usage 
declare resource control _$reserve entry (pointer, pointer, bit (1) aligned, 
bit (72) aligned, fixed bin (35)))3 


call resource control $reserve (descriptions ptr, reservation_desc_ptr, 
authorization, system, code); 


where: 

Ve descriptions ptr (Input) 
is a pointer to the structure containing a description of the 
resources to be reserved (see “Resource Description" below). 

2. reservation_dese ptr (Input) 
is a pointer to the structure containing reservation information for 
the resources to be reserved (see "Reservation Description" below). 

ce authorization (Input) 
checks the user's authorization to use the devices or volumes and is 
only valid if system = "1"b. 

4, system (Input) 
specifies, if "1i"b, that the calling process wishes to perform a 
privileged reservation (see "Notes" below). 

5. code (Out put ) 


is a standard status code. 
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Reservation Description 


The reservation_desc_ ptr argument points to the following structure 
(declared in the include file resource control desc.incl.pl1): 


del 1 reservation_description aligned based, 
2 version_no fixed bin, 
2 reserved _for char (32), 
2 reserved_by char (32), 
2 reservation_id fixed bin (71), 
2 group_starting time fixed bin (71), 
2 asap_duration fixed bin (71), 
2 flags aligned, 


(3 auto_expire bit (1), 
3 asap bit (1), 
3 rel bit (1), 
3 sec bit (1)) unaligned, 
2 n_items fixed bin, 
2 reservation_group (Resource_count refer 
(reservation_description.n_items)), 
3 starting time fixed bin (71), 
3 duration fixed bin (71); 


where: 
i. version_no (Input) 
is the current version number of this structure. It should be set 
to "resource control _version_1". 
2. reserved for Input) 
specifies the User_id of the process for whom this reservation is 
made. The use of an asterisk (*) for a component name is permitted. 
If this element is blanks, the User_id of the current process is 
used. 
3. reserved_by (Input) 
is the User_id of the process which is charged for this reservation 
(see "Notes" below). This element is ignored for an unprivileged 
reservation and the current User_id is used. 
4. reservation_id (Input or Output) 
is an identifier for this reservation group. It is currently 
returned as an absolute clock time. 
5. n_items (Input) 


is the number of items being reserved. 


The rest of the items in this structure are currently ignored and should be set 
to zero. 


Notes 


If system = "i"b, reservation_description.reserved_ by is used to specify 
the User_id of the process to be charged for this reservation. 
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The reservation description structure is strongly dependent on the 
resource descriptions structure. That is, for each resource described in 
resource descriptions there must be a corresponding entry of the same index in 
reservation description. 


Access Restrictions 


Execute access to the rep_sys_ gate is necessary to perform a privileged 
reservation. 


Entry: resource_control_ $cancel_id_ string 


This entry point cancels the reservation of a resource or. group of 
resources. 


Usage 
declare resource control _ $cancel id string entry (char(*), char(*), 
bit(1) aligned, fixed bin (35)); 
eall resource_control_$cancel id string (reservation_id, group _id, system, 
code); 
where: 
1. reservation_id (Input) 
is the character string representation of the reservation identifier 
to be cancelled. 
2 group id (Input) 
is the group id of the user to whom the reservation belongs. This 
is only valid if system = "1"b. 
3. system (Input) 
specifies, if "1"b, that a privileged cancellation is to be 


performed (see "Notes" below). 


Hee code (Out put) 
is a standard status code. 


Notes 


If system = "1"b, then the reservation group is foreibly cancelled whether 
or not it belongs to the current process. 
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Access Restrictions 


Execute access to the rep _sys_ gate is necessary to perform a privileged 
cancellation. 


Resource Description 


The descriptions ptr argument points to the following structure (this 
structure is declared in the include file resource _control_desc.inel.pl1): 


del 1 resource_descriptions based (resource_desc_ptr) aligned, 
version_no fixed bin, 
n_items fixed bin, 
item (Resource count refer (resource_descriptions.n_items)) aligned, 
type char (32), 
name char (32), 
uid bit €36). 
potential attributes bit (72), 
attributes (2) bit (72), 
desired_attributes (4) bit (72), 
potential_aim range (2) bit (72), 
aim_range (2) bit (72), 
owner char (32), 
acs path char (168), 
location char (168), 
comment char (168), 
charge type char (32), 
rew bit (3) unaligned, 
(usage_lock, 
release _lock, 
awaiting clear, 
user_alloc) bit (1) unaligned, 
3 pad2 bit (29) unaligned, 
3 given aligned, 
(4 (name, 
uid, 
potential attributes, 
desired attributes, 
potential _ aim range, 
aim_range, 
owner, 
acs_ path, 
location, 
comment, 
charge type, 
usage_lock, 
release lock, 
user_alloc) bit (1), 
4 padi bit (22)) unaligned, 
3 state bit (36) aligned, 
3 status_code fixed bin (35); 


PM PM 
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where: 
1. version_no (Input) 
is the current version number of the structure. It should be set to 
"resource control _version_1". 
2. n_items (Input) 
specifies the number of resources described by this structure. A 
consistent combination of the following elements must be supplied 
for each resource described. 
3. type (Input) 
specifies the type of resource desired (e.g., tape, disk drive). It 
must be supplied (see "Notes" below). 
4, name (Input or Output) 
is a specific resource name. If flags.name given = "1"b, the named 
resource is chosen. If flags.name given = "0O"b, a resource is 
chosen depending on criteria specified by other elements’) of the 
structure, and the name of the resource chosen is returned in this 
element (see "Notes" below). 
Be vid (Input or Output) 
is the unique identifier of a specific resource. if 
flags.uid_given = "1"b, the specified resource is chosen. Lt 
flags.-uid_given = "0"b, a resource is chosen depending on criteria 
specified by other elements of the structure, and the unique 
identifier of the resource chosen is returned in this element. 
6. potential_attributes (Output) 
specifies the potential attributes of the resource chosen. 
7. attributes (Input or Output) 
contains, if flags.attr_given = "1"b, the specification of 
attributes which the resource chosen must possess. Lt 
flags.attr_given = "0"b, the resource to be chosen need not possess 
any particular attributes. The attributes of the resource chosen 
are returned in these elements (see "Notes" below). 
8. desired attributes (Input) 
specifies the desired attributes of the resource chosen. 
9. potential_aim_bounds (Output) 
are a pair of AIM access classes, specifying the minimum and maximum 
process authorization that can be permitted to acquire this 
resource. 
10. aim_bounds (Input or Output) 
are a pair of AIM access classes, specifying the minimum and maximum 
process authorization that can be permitted to both read and write 
this resource. If flags.aim_bounds_ given = "i"b, this element is 
input. Otherwise, it is output. 
11. owner (Input or Output) 
is the owner of the resource. If flags.owner = "1"b, this element 
is input. Otherwise, this element is output (see "Notes" and 
"Access Restrictions" below). 
12. acs path (Input) 


is the pathname of the access control segment (ACS) for this 
resource (see "Access Restrictions" below). 
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13. location (Out put ) 
contains a character string description of the location of this 
resource. 

14. comment (Input) 


contains a character-string comment which is associated with this 
resource. 


15. charge type (Input) 
is the accounting identifier for this resource. 


16. rew (Output) 
is the effective access of the user to this resource. 


17. usage_lock (Input) 
if "1"b, specifies that this resource cannot be used by any user, 
regardless of the state of the resource. 


18. release lock (Input) 
if "1"b, specifies that the owner of the resource is not allowed to 
release the resource. Unless system = "1"b, this element is ignored 


(see "Notes" below). 


19. awaiting clear (Out put ) 
specifies that the resource is awaiting manual clear. 
20. user_alloc (Input) 
if "1"b, specifies that the user has not allocated the resource to 
any use. 
21. pad2 (Input) 
is unused and must be zero. 
22. name (Input) 
is "1"b if item.name has been supplied by the caller. 
23. uid (Input) 
is "1"b if item.uid has been supplied by the caller. 
24. potential_attr (Input) 
is "I"b, if item.potential attributes has been supplied by the 
caller. 
25. desired_attr (Input) 


is "1"b if item.desired_ attributes has been supplied by the caller. 
26. potential_aim_ bounds (Input) 

is "1"b if item.potential_aim_bounds has been supplied by the 

caller. 


27. aim_bounds (Input) 
is "1"b if item.aim_bounds has been supplied by the caller. 


28. owner (Input) 
is "i"b if item.owner has been supplied by the caller. 


29. acs _path (Input) 
is "i"b if item.acs path has been supplied by the caller. 


30. location (Input) 
is "1"b if item.location has been supplied by the caller. 
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31. comment (Input) 
is "1"b if item.comment has been supplied by the caller. 


32. charge type (Input) 
is "1"b if item.charge type given has been supplied by the caller. 
33. usage_lock (Input) 
is "1"b if item.usage lock has been supplied by the caller. 
34. release_lock (Input ) 
is "1"b if item.release lock has been supplied by the caller. 
35. user_alloc (Input) 
is "1"b if item.user_alloec given has been supplied by the caller. 
36. padi (Input) 
is unused and must be zero. 
37. state (Output ) 
is for the use of resource_control_ and should not be used by the 
user. 
38. status_code (Output ) 
is a standard status’ code. If the subroutine argument code is 


nonzero, one or more items in the structure have a nonzero 
status_code specifying in more detail why the attempt to manipulate 
the described resource was refused. 


Notes 


Bhs 


A list of defined resource types may be obtained via the 
list_resource_ types command. 


Suitable values for the attributes element may be constructed using the 
cv_rep attributes $from_string subroutine. 


Access Restrictions 


The user must have at least sm permission to the directory in which the ACS 
is specified to reside. 


Unless otherwise stated, the user must have re access to the rep_sys_ gate 
to specify system = "1"b in the calling sequence for any entry point of the 
resource_control_ subroutine. 
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Name: resource info_ 


The resource_info_ subroutine returns selected information about RCP 


resource types defined on the system. 


Entry: resource_info_$get_type 


This entry point, given the name of a resource type, indicates whether the 
resource type named is a device or a volume. 


Usage 


declare resource_info $get_type entry (char (¥*), bit (1), fixed bin (35)); 


eall resource_info $get_type (name, is_volume, code); 


where: 
= name (Input) 
is the name of a defined resource type (see "Notes" below). 
ED is_volume (Output ) 
is "1"b if the resource type given specifies a class of volumes. If 
"O"b, the resource type given specifies a class of devices. 
a code (Output) 
is a standard status code. 
Notes 


A list of defined resource types may be obtained via the 
list_resource types command (see Section 4). 


Entry: resource_info_$limits 


This entry point returns information about quantity and time limits fora 
given resource type. 
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Usage 


declare resource info $limits entry (char (*), fixed bin, fixed bin, 
fixed bin, fixed bin (35)); 


eall resource_info_ $limits (name, max_quantity, default_time, max_time, 


code); 
where: 
Ts name (Input) 
is the name of a defined resource type. 
2. max_quantity (Output) 
is the maximum number of this type of resource that a process may 
assign at one time. 
3. default_time | (Output ) 
is the default reservation time, in minutes, for this type of 
resource. 
4. max_time (Cut put) 
is the maximum allowed reservation time, in minutes, for this type 
of resource. 
5. code (Output) 
is a standard status code. 
Notes 


The information returned by this entry point is from the RTDT. These are 


not the limits currently enforced by RCP (see "Device Limits" in Section 1). 


Entry: resource info $mates 


This entry provides information about the resource type or types with which 
the given resource type may be mounted. 


Usage 
declare resource info $mates entry (char (*), fixed bin, char (*) 
dimension (*), fixed bin (35))3 


call resource _info_$mates (name, n_mates, mates, code); 
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where: 
1. name (Input) 
is the name of a defined resource type. 
2. mn mates (Output ) 
is the number of mates returned. 
3. mates (Output) 
contains the name or names of the resource type(s) that may be 
mounted with this resource (see "Notes" below). 
4, code (Output ) 
is a standard status code. 
Notes 


If the number of elements in mates is too small to hold all the mates for 
the given resource type, code is set to error _table $smallarg and mates is set 
to the null string. However, n_mates still contains the number of mates 
associated with the given resource type. 


Entry: resource _info $defaults 


This entry point fills a resource_descriptions structure with the default 
registration parameters defined in the RTDT. 


Usage 


del resource info $defaults entry (char(*), char(*), pointer, 
fixed bin(35)); 


call resource_info_ $defaults (name, subtype, item_ptr, code); 


where: 
de name (Input) 

is the name of a defined resource type. 
2. subtype (Input) 


is the name of a subtype of the resource type, defined in the RTDT. 
If subtype is the null string, the master defaults for the resource 
type are used. 


36 item ptr 
points to a structure declared like resource _descriptions.item (see 
the resource_control_ subroutine). 


4, code (Output) 
is a standard status code. 
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Entry: resource _info_$lock_on release 


This entry point returns a value specifying whether resources of a given 
type are to be locked for manual clearing at release time. 


Usage 


del resource_info $lock_on_release entry (char(*), bit(1) aligned, 
fixed bin(35)); 


call resource_info_$lock_on_release (name, lock sw, code); 


where: 
1. name (Input) 
is the name of a defined resource type. 
2. lock_sw (Output) 
specifies whether the resource is locked at release time. 
aes Bd 8 lock the resource 
"OCOb do not lock the resource 
3. eode (Out put ) 


is a standard status code. 


Entry: resource_info_$canonicalize_ name 


This entry point applies the proper canonicalization to a resource name of 
a given resource type. See "Canonicalization Routines" in the MAM RCP. 


Usage 


declare resource_info_ $canonicalize_name entry (char(*), char(*), char(*), 
fixed bin(35)); 


call resource_info_$canonicalize_name (resource type, resource_name, 
canonicalized_name, code); 
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where: 
V2 resource type (Input) 
is the name of a defined resource type. 
2 resource name (Input) 
is the string to be canonicalized. 
3. canonicalized_name (Out put) 
is the canonicalized representation of resource name. 
4, code (Output ) 


is a standard status code. 
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